{
  "cells": [
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "N7ITxKLUkX0v"
      },
      "source": [
        "##### Copyright 2020 The TensorFlow Authors."
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "cellView": "form",
        "id": "yOYx6tzSnWQ3"
      },
      "outputs": [],
      "source": [
        "#@title Licensed under the Apache License, Version 2.0 (the \"License\");\n",
        "# you may not use this file except in compliance with the License.\n",
        "# You may obtain a copy of the License at\n",
        "#\n",
        "# https://www.apache.org/licenses/LICENSE-2.0\n",
        "#\n",
        "# Unless required by applicable law or agreed to in writing, software\n",
        "# distributed under the License is distributed on an \"AS IS\" BASIS,\n",
        "# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n",
        "# See the License for the specific language governing permissions and\n",
        "# limitations under the License."
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "6xgB0Oz5eGSQ"
      },
      "source": [
        "# 函数式 API"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "w4zzZVZtQb1w"
      },
      "source": [
        "<table class=\"tfo-notebook-buttons\" align=\"left\">\n",
        "  <td><a target=\"_blank\" href=\"https://tensorflow.google.cn/guide/keras/functional\" class=\"\"><img src=\"https://tensorflow.google.cn/images/tf_logo_32px.png\" class=\"\">在 TensorFlow.org 上查看</a></td>\n",
        "  <td><a target=\"_blank\" href=\"https://colab.research.google.com/github/tensorflow/docs-l10n/blob/master/site/zh-cn/guide/keras/functional.ipynb\" class=\"\"><img src=\"https://tensorflow.google.cn/images/colab_logo_32px.png\" class=\"\">在 Google Colab 中运行</a></td>\n",
        "  <td><a target=\"_blank\" href=\"https://github.com/tensorflow/docs-l10n/blob/master/site/zh-cn/guide/keras/functional.ipynb\" class=\"\"><img src=\"https://tensorflow.google.cn/images/GitHub-Mark-32px.png\" class=\"\">在 GitHub 上查看源代码</a></td>\n",
        "  <td><a href=\"https://storage.googleapis.com/tensorflow_docs/docs-l10n/site/zh-cn/guide/keras/functional.ipynb\" class=\"\"><img src=\"https://tensorflow.google.cn/images/download_logo_32px.png\" class=\"\">下载笔记本</a></td>\n",
        "</table>"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "MhDp9kY2uRS6"
      },
      "source": [
        "## 设置"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "id": "6MDMqZmJeOHN"
      },
      "outputs": [],
      "source": [
        "import numpy as np\n",
        "import tensorflow as tf\n",
        "from tensorflow import keras\n",
        "from tensorflow.keras import layers"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "KXceA9P5NdRb"
      },
      "source": [
        "## 简介\n",
        "\n",
        "Keras *函数式 API* 是一种比 `tf.keras.Sequential` API 更加灵活的模型创建方式。函数式 API 可以处理具有非线性拓扑的模型、具有共享层的模型，以及具有多个输入或输出的模型。\n",
        "\n",
        "深度学习模型通常是层的有向无环图 (DAG)。因此，函数式 API 是构建*层计算图*的一种方式。\n",
        "\n",
        "请考虑以下模型：\n",
        "\n",
        "```\n",
        "(input: 784-dimensional vectors)        ↧ [Dense (64 units, relu activation)]        ↧ [Dense (64 units, relu activation)]        ↧ [Dense (10 units, softmax activation)]        ↧ (output: logits of a probability distribution over 10 classes)\n",
        "```\n",
        "\n",
        "这是一个具有三层的基本计算图。要使用函数式 API 构建此模型，请先创建一个输入节点："
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "id": "OmmgsmCV6ZKu"
      },
      "outputs": [],
      "source": [
        "inputs = keras.Input(shape=(784,))"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "aY7NvBKYoJcX"
      },
      "source": [
        "数据的形状设置为 784 维向量。由于仅指定了每个样本的形状，因此始终忽略批次大小。\n",
        "\n",
        "例如，如果您有一个形状为 `(32, 32, 3)` 的图像输入，则可以使用："
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "id": "JUPt25nNlHHH"
      },
      "outputs": [],
      "source": [
        "# Just for demonstration purposes.\n",
        "img_inputs = keras.Input(shape=(32, 32, 3))"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "lXQdVFTVLD5b"
      },
      "source": [
        "返回的 `inputs` 包含馈送给模型的输入数据的形状和 `dtype`。形状如下："
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "id": "ZHFIWPU7wVJZ"
      },
      "outputs": [],
      "source": [
        "inputs.shape"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "KPqqeTi8d5ku"
      },
      "source": [
        "dtype 如下："
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "id": "0fmC8I1q4dJj"
      },
      "outputs": [],
      "source": [
        "inputs.dtype"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "BwMT467cBsVj"
      },
      "source": [
        "可以通过在此 `inputs` 对象上调用层，在层计算图中创建新的节点："
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "id": "dODwyenwQRPM"
      },
      "outputs": [],
      "source": [
        "dense = layers.Dense(64, activation=\"relu\")\n",
        "x = dense(inputs)"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "qTnmiEzNBJqk"
      },
      "source": [
        "“层调用”操作就像从“输入”向您创建的该层绘制一个箭头。您将输入“传递”到 `dense` 层，然后得到 `x`。\n",
        "\n",
        "让我们为层计算图多添加几个层："
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "id": "oT1vzNmZW9N7"
      },
      "outputs": [],
      "source": [
        "x = layers.Dense(64, activation=\"relu\")(x)\n",
        "outputs = layers.Dense(10)(x)"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "A7kTENSOucbI"
      },
      "source": [
        "此时，您可以通过在层计算图中指定模型的输入和输出来创建 `Model`："
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "id": "MmPBtW89IuXz"
      },
      "outputs": [],
      "source": [
        "model = keras.Model(inputs=inputs, outputs=outputs, name=\"mnist_model\")"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "3wo6t5CLy9Oy"
      },
      "source": [
        "让我们看看模型摘要是什么样子："
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "id": "jN0rWVpy0TfD"
      },
      "outputs": [],
      "source": [
        "model.summary()"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "Savf17rFH0M6"
      },
      "source": [
        "您还可以将模型绘制为计算图："
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "id": "yic28GLymOCh"
      },
      "outputs": [],
      "source": [
        "keras.utils.plot_model(model, \"my_first_model.png\")"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "QptdFYTnwIv7"
      },
      "source": [
        "并且，您还可以选择在绘制的计算图中显示每层的输入和输出形状："
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "id": "rLgR2R8jGXLQ"
      },
      "outputs": [],
      "source": [
        "keras.utils.plot_model(model, \"my_first_model_with_shape_info.png\", show_shapes=True)"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "PcPJFsbjjDf6"
      },
      "source": [
        "此图和代码几乎完全相同。在代码版本中，连接箭头由调用操作代替。\n",
        "\n",
        "“层计算图”是深度学习模型的直观心理图像，而函数式 API 是创建密切反映此图像的模型的方法。"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "3PUNF7DVUblY"
      },
      "source": [
        "## 训练、评估和推断\n",
        "\n",
        "对于使用函数式 API 构建的模型来说，其训练、评估和推断的工作方式与 `Sequential` 模型完全相同。\n",
        "\n",
        "如下所示，加载 MNIST 图像数据，将其改造为向量，将模型与数据拟合（同时监视验证拆分的性能），然后在测试数据上评估模型："
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "id": "mkpWoPcTOZCD"
      },
      "outputs": [],
      "source": [
        "(x_train, y_train), (x_test, y_test) = keras.datasets.mnist.load_data()\n",
        "\n",
        "x_train = x_train.reshape(60000, 784).astype(\"float32\") / 255\n",
        "x_test = x_test.reshape(10000, 784).astype(\"float32\") / 255\n",
        "\n",
        "model.compile(\n",
        "    loss=keras.losses.SparseCategoricalCrossentropy(from_logits=True),\n",
        "    optimizer=keras.optimizers.RMSprop(),\n",
        "    metrics=[\"accuracy\"],\n",
        ")\n",
        "\n",
        "history = model.fit(x_train, y_train, batch_size=64, epochs=2, validation_split=0.2)\n",
        "\n",
        "test_scores = model.evaluate(x_test, y_test, verbose=2)\n",
        "print(\"Test loss:\", test_scores[0])\n",
        "print(\"Test accuracy:\", test_scores[1])"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "TZzRtWubSBwY"
      },
      "source": [
        "有关更多信息，请参阅[训练和评估](https://tensorflow.google.cn/guide/keras/train_and_evaluate/)指南。"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "OgYkfTa6tOQ2"
      },
      "source": [
        "## 保存和序列化\n",
        "\n",
        "对于使用函数式 API 构建的模型，其保存模型和序列化的工作方式与 `Sequential` 模型相同。保存函数式模型的标准方式是调用 `model.save()` 将整个模型保存为单个文件。您可以稍后从该文件重新创建相同的模型，即使构建该模型的代码已不再可用。\n",
        "\n",
        "保存的文件包括：\n",
        "\n",
        "- 模型架构\n",
        "- 模型权重值（在训练过程中得知）\n",
        "- 模型训练配置（如果有的话，如传递给 `compile`）\n",
        "- 优化器及其状态（如果有的话，用来从上次中断的地方重新开始训练）"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "id": "mkRmgfkJP6zK"
      },
      "outputs": [],
      "source": [
        "model.save(\"path_to_my_model\")\n",
        "del model\n",
        "# Recreate the exact same model purely from the file:\n",
        "model = keras.models.load_model(\"path_to_my_model\")"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "Mp765dBoRYAv"
      },
      "source": [
        "有关详细信息，请阅读模型[序列化和保存](https://tensorflow.google.cn/guide/keras/save_and_serialize/)指南。"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "2JDEVmeee2PQ"
      },
      "source": [
        "## 使用相同的层计算图定义多个模型\n",
        "\n",
        "在函数式 API 中，模型是通过在层计算图中指定其输入和输出来创建的。这意味着可以使用单个层计算图来生成多个模型。\n",
        "\n",
        "在下面的示例中，您将使用相同的层堆栈来实例化两个模型：能够将图像输入转换为 16 维向量的 `encoder` 模型，以及用于训练的端到端 `autoencoder` 模型。"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "id": "ixrLyba7ZR68"
      },
      "outputs": [],
      "source": [
        "encoder_input = keras.Input(shape=(28, 28, 1), name=\"img\")\n",
        "x = layers.Conv2D(16, 3, activation=\"relu\")(encoder_input)\n",
        "x = layers.Conv2D(32, 3, activation=\"relu\")(x)\n",
        "x = layers.MaxPooling2D(3)(x)\n",
        "x = layers.Conv2D(32, 3, activation=\"relu\")(x)\n",
        "x = layers.Conv2D(16, 3, activation=\"relu\")(x)\n",
        "encoder_output = layers.GlobalMaxPooling2D()(x)\n",
        "\n",
        "encoder = keras.Model(encoder_input, encoder_output, name=\"encoder\")\n",
        "encoder.summary()\n",
        "\n",
        "x = layers.Reshape((4, 4, 1))(encoder_output)\n",
        "x = layers.Conv2DTranspose(16, 3, activation=\"relu\")(x)\n",
        "x = layers.Conv2DTranspose(32, 3, activation=\"relu\")(x)\n",
        "x = layers.UpSampling2D(3)(x)\n",
        "x = layers.Conv2DTranspose(16, 3, activation=\"relu\")(x)\n",
        "decoder_output = layers.Conv2DTranspose(1, 3, activation=\"relu\")(x)\n",
        "\n",
        "autoencoder = keras.Model(encoder_input, decoder_output, name=\"autoencoder\")\n",
        "autoencoder.summary()"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "pdIJ7h2Pz9rH"
      },
      "source": [
        "在上例中，解码架构与编码架构严格对称，因此输出形状与输入形状 `(28, 28, 1)` 相同。\n",
        "\n",
        "`Conv2D` 层的反面是 `Conv2DTranspose` 层，`MaxPooling2D` 层的反面是 `UpSampling2D` 层。"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "J6sjS6a22AtF"
      },
      "source": [
        "## 所有模型均可像层一样调用\n",
        "\n",
        "您可以通过在 `Input` 上或在另一个层的输出上调用任何模型来将其当作层来处理。通过调用模型，您不仅可以重用模型的架构，还可以重用它的权重。\n",
        "\n",
        "为了查看实际运行情况，下面是对自动编码器示例的另一种处理方式，该示例创建了一个编码器模型、一个解码器模型，并在两个调用中将它们链接，以获得自动编码器模型："
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "id": "xcXQuaWMdfWY"
      },
      "outputs": [],
      "source": [
        "encoder_input = keras.Input(shape=(28, 28, 1), name=\"original_img\")\n",
        "x = layers.Conv2D(16, 3, activation=\"relu\")(encoder_input)\n",
        "x = layers.Conv2D(32, 3, activation=\"relu\")(x)\n",
        "x = layers.MaxPooling2D(3)(x)\n",
        "x = layers.Conv2D(32, 3, activation=\"relu\")(x)\n",
        "x = layers.Conv2D(16, 3, activation=\"relu\")(x)\n",
        "encoder_output = layers.GlobalMaxPooling2D()(x)\n",
        "\n",
        "encoder = keras.Model(encoder_input, encoder_output, name=\"encoder\")\n",
        "encoder.summary()\n",
        "\n",
        "decoder_input = keras.Input(shape=(16,), name=\"encoded_img\")\n",
        "x = layers.Reshape((4, 4, 1))(decoder_input)\n",
        "x = layers.Conv2DTranspose(16, 3, activation=\"relu\")(x)\n",
        "x = layers.Conv2DTranspose(32, 3, activation=\"relu\")(x)\n",
        "x = layers.UpSampling2D(3)(x)\n",
        "x = layers.Conv2DTranspose(16, 3, activation=\"relu\")(x)\n",
        "decoder_output = layers.Conv2DTranspose(1, 3, activation=\"relu\")(x)\n",
        "\n",
        "decoder = keras.Model(decoder_input, decoder_output, name=\"decoder\")\n",
        "decoder.summary()\n",
        "\n",
        "autoencoder_input = keras.Input(shape=(28, 28, 1), name=\"img\")\n",
        "encoded_img = encoder(autoencoder_input)\n",
        "decoded_img = decoder(encoded_img)\n",
        "autoencoder = keras.Model(autoencoder_input, decoded_img, name=\"autoencoder\")\n",
        "autoencoder.summary()"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "d0WxZBNAzEla"
      },
      "source": [
        "如您所见，模型可以嵌套：模型可以包含子模型（因为模型就像层一样）。模型嵌套的一个常见用例是*装配*。例如，以下展示了如何将一组模型装配成一个平均其预测的模型："
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "id": "F9R2lmeBmf9J"
      },
      "outputs": [],
      "source": [
        "def get_model():\n",
        "    inputs = keras.Input(shape=(128,))\n",
        "    outputs = layers.Dense(1)(inputs)\n",
        "    return keras.Model(inputs, outputs)\n",
        "\n",
        "\n",
        "model1 = get_model()\n",
        "model2 = get_model()\n",
        "model3 = get_model()\n",
        "\n",
        "inputs = keras.Input(shape=(128,))\n",
        "y1 = model1(inputs)\n",
        "y2 = model2(inputs)\n",
        "y3 = model3(inputs)\n",
        "outputs = layers.average([y1, y2, y3])\n",
        "ensemble_model = keras.Model(inputs=inputs, outputs=outputs)"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "OHYZkAo4M1f9"
      },
      "source": [
        "## 处理复杂的计算图拓扑\n",
        "\n",
        "### 具有多个输入和输出的模型\n",
        "\n",
        "函数式 API 使处理多个输入和输出变得容易。而这无法使用 `Sequential` API 处理。\n",
        "\n",
        "例如，如果您要构建一个系统，该系统按照优先级对自定义问题工单进行排序，然后将工单传送到正确的部门，则此模型将具有三个输入：\n",
        "\n",
        "- 工单标题（文本输入），\n",
        "- 工单的文本正文（文本输入），以及\n",
        "- 用户添加的任何标签（分类输入）\n",
        "\n",
        "此模型将具有两个输出：\n",
        "\n",
        "- 介于 0 和 1 之间的优先级分数（标量 Sigmoid 输出），以及\n",
        "- 应该处理工单的部门（部门范围内的 Softmax 输出）。\n",
        "\n",
        "您可以使用函数式 API 通过几行代码构建此模型："
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "id": "oGlBbB98HIWt"
      },
      "outputs": [],
      "source": [
        "num_tags = 12  # Number of unique issue tags\n",
        "num_words = 10000  # Size of vocabulary obtained when preprocessing text data\n",
        "num_departments = 4  # Number of departments for predictions\n",
        "\n",
        "title_input = keras.Input(\n",
        "    shape=(None,), name=\"title\"\n",
        ")  # Variable-length sequence of ints\n",
        "body_input = keras.Input(shape=(None,), name=\"body\")  # Variable-length sequence of ints\n",
        "tags_input = keras.Input(\n",
        "    shape=(num_tags,), name=\"tags\"\n",
        ")  # Binary vectors of size `num_tags`\n",
        "\n",
        "# Embed each word in the title into a 64-dimensional vector\n",
        "title_features = layers.Embedding(num_words, 64)(title_input)\n",
        "# Embed each word in the text into a 64-dimensional vector\n",
        "body_features = layers.Embedding(num_words, 64)(body_input)\n",
        "\n",
        "# Reduce sequence of embedded words in the title into a single 128-dimensional vector\n",
        "title_features = layers.LSTM(128)(title_features)\n",
        "# Reduce sequence of embedded words in the body into a single 32-dimensional vector\n",
        "body_features = layers.LSTM(32)(body_features)\n",
        "\n",
        "# Merge all available features into a single large vector via concatenation\n",
        "x = layers.concatenate([title_features, body_features, tags_input])\n",
        "\n",
        "# Stick a logistic regression for priority prediction on top of the features\n",
        "priority_pred = layers.Dense(1, name=\"priority\")(x)\n",
        "# Stick a department classifier on top of the features\n",
        "department_pred = layers.Dense(num_departments, name=\"department\")(x)\n",
        "\n",
        "# Instantiate an end-to-end model predicting both priority and department\n",
        "model = keras.Model(\n",
        "    inputs=[title_input, body_input, tags_input],\n",
        "    outputs=[priority_pred, department_pred],\n",
        ")"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "gT7OusdT4Fx0"
      },
      "source": [
        "现在绘制模型："
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "id": "ubXxLLv6Sng5"
      },
      "outputs": [],
      "source": [
        "keras.utils.plot_model(model, \"multi_input_and_output_model.png\", show_shapes=True)"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "IbS8dzSHzcZz"
      },
      "source": [
        "编译此模型时，可以为每个输出分配不同的损失。甚至可以为每个损失分配不同的权重，以调整其对总训练损失的贡献。"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "id": "aPcRNBUDfuMH"
      },
      "outputs": [],
      "source": [
        "model.compile(\n",
        "    optimizer=keras.optimizers.RMSprop(1e-3),\n",
        "    loss=[\n",
        "        keras.losses.BinaryCrossentropy(from_logits=True),\n",
        "        keras.losses.CategoricalCrossentropy(from_logits=True),\n",
        "    ],\n",
        "    loss_weights=[1.0, 0.2],\n",
        ")"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "NCJG9nfDLR2X"
      },
      "source": [
        "由于输出层具有不同的名称，您还可以像下面这样指定损失："
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "id": "xVxcjjgoZNAk"
      },
      "outputs": [],
      "source": [
        "model.compile(\n",
        "    optimizer=keras.optimizers.RMSprop(1e-3),\n",
        "    loss={\n",
        "        \"priority\": keras.losses.BinaryCrossentropy(from_logits=True),\n",
        "        \"department\": keras.losses.CategoricalCrossentropy(from_logits=True),\n",
        "    },\n",
        "    loss_weights=[1.0, 0.2],\n",
        ")"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "imQ0qyEvexNn"
      },
      "source": [
        "通过传递输入和目标的 NumPy 数组列表来训练模型："
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "id": "k0M4ErZIZfR7"
      },
      "outputs": [],
      "source": [
        "# Dummy input data\n",
        "title_data = np.random.randint(num_words, size=(1280, 10))\n",
        "body_data = np.random.randint(num_words, size=(1280, 100))\n",
        "tags_data = np.random.randint(2, size=(1280, num_tags)).astype(\"float32\")\n",
        "\n",
        "# Dummy target data\n",
        "priority_targets = np.random.random(size=(1280, 1))\n",
        "dept_targets = np.random.randint(2, size=(1280, num_departments))\n",
        "\n",
        "model.fit(\n",
        "    {\"title\": title_data, \"body\": body_data, \"tags\": tags_data},\n",
        "    {\"priority\": priority_targets, \"department\": dept_targets},\n",
        "    epochs=2,\n",
        "    batch_size=32,\n",
        ")"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "rEqjUgWn45jT"
      },
      "source": [
        "当使用 `Dataset` 对象调用拟合时，它应该会生成一个列表元组（如 `([title_data, body_data, tags_data], [priority_targets, dept_targets])` 或一个字典元组（如 `({'title': title_data, 'body': body_data, 'tags': tags_data}, {'priority': priority_targets, 'department': dept_targets})`）。\n",
        "\n",
        "有关详细说明，请参阅[训练和评估](https://tensorflow.google.cn/guide/keras/train_and_evaluate/)指南。"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "SkjcQadpYwht"
      },
      "source": [
        "### 小 ResNet 模型\n",
        "\n",
        "除了具有多个输入和输出的模型外，函数式 API 还使处理非线性连接拓扑（这些模型的层没有按顺序连接）变得容易。这是 `Sequential` API 无法处理的。\n",
        "\n",
        "关于这一点的一个常见用例是残差连接。让我们来为 CIFAR10 构建一个小 ResNet 模型以进行演示："
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "id": "mQeUGBNHK7yU"
      },
      "outputs": [],
      "source": [
        "inputs = keras.Input(shape=(32, 32, 3), name=\"img\")\n",
        "x = layers.Conv2D(32, 3, activation=\"relu\")(inputs)\n",
        "x = layers.Conv2D(64, 3, activation=\"relu\")(x)\n",
        "block_1_output = layers.MaxPooling2D(3)(x)\n",
        "\n",
        "x = layers.Conv2D(64, 3, activation=\"relu\", padding=\"same\")(block_1_output)\n",
        "x = layers.Conv2D(64, 3, activation=\"relu\", padding=\"same\")(x)\n",
        "block_2_output = layers.add([x, block_1_output])\n",
        "\n",
        "x = layers.Conv2D(64, 3, activation=\"relu\", padding=\"same\")(block_2_output)\n",
        "x = layers.Conv2D(64, 3, activation=\"relu\", padding=\"same\")(x)\n",
        "block_3_output = layers.add([x, block_2_output])\n",
        "\n",
        "x = layers.Conv2D(64, 3, activation=\"relu\")(block_3_output)\n",
        "x = layers.GlobalAveragePooling2D()(x)\n",
        "x = layers.Dense(256, activation=\"relu\")(x)\n",
        "x = layers.Dropout(0.5)(x)\n",
        "outputs = layers.Dense(10)(x)\n",
        "\n",
        "model = keras.Model(inputs, outputs, name=\"toy_resnet\")\n",
        "model.summary()"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "8zfmZlT1xTn8"
      },
      "source": [
        "绘制模型："
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "id": "SHQ6dU6pgsJu"
      },
      "outputs": [],
      "source": [
        "keras.utils.plot_model(model, \"mini_resnet.png\", show_shapes=True)"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "su4s6cqAuvSf"
      },
      "source": [
        "现在训练模型："
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "id": "P5IWLrIrc4u4"
      },
      "outputs": [],
      "source": [
        "(x_train, y_train), (x_test, y_test) = keras.datasets.cifar10.load_data()\n",
        "\n",
        "x_train = x_train.astype(\"float32\") / 255.0\n",
        "x_test = x_test.astype(\"float32\") / 255.0\n",
        "y_train = keras.utils.to_categorical(y_train, 10)\n",
        "y_test = keras.utils.to_categorical(y_test, 10)\n",
        "\n",
        "model.compile(\n",
        "    optimizer=keras.optimizers.RMSprop(1e-3),\n",
        "    loss=keras.losses.CategoricalCrossentropy(from_logits=True),\n",
        "    metrics=[\"acc\"],\n",
        ")\n",
        "# We restrict the data to the first 1000 samples so as to limit execution time\n",
        "# on Colab. Try to train on the entire dataset until convergence!\n",
        "model.fit(x_train[:1000], y_train[:1000], batch_size=64, epochs=1, validation_split=0.2)"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "1d7iBF4FPYKv"
      },
      "source": [
        "## 共享层\n",
        "\n",
        "函数式 API 的另一个很好的用途是使用*共享层*的模型。共享层是在同一个模型中多次重用的层实例，它们会学习与层计算图中的多个路径相对应的特征。\n",
        "\n",
        "共享层通常用于对来自相似空间（例如，两个具有相似词汇的不同文本）的输入进行编码。它们可以实现在这些不同的输入之间共享信息，以及在更少的数据上训练这种模型。如果在其中的一个输入中看到了一个给定单词，那么将有利于处理通过共享层的所有输入。\n",
        "\n",
        "要在函数式 API 中共享层，请多次调用同一个层实例。例如，下面是一个在两个不同文本输入之间共享的 `Embedding` 层："
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "id": "kMyHQbCeLm4S"
      },
      "outputs": [],
      "source": [
        "# Embedding for 1000 unique words mapped to 128-dimensional vectors\n",
        "shared_embedding = layers.Embedding(1000, 128)\n",
        "\n",
        "# Variable-length sequence of integers\n",
        "text_input_a = keras.Input(shape=(None,), dtype=\"int32\")\n",
        "\n",
        "# Variable-length sequence of integers\n",
        "text_input_b = keras.Input(shape=(None,), dtype=\"int32\")\n",
        "\n",
        "# Reuse the same layer to encode both inputs\n",
        "encoded_input_a = shared_embedding(text_input_a)\n",
        "encoded_input_b = shared_embedding(text_input_b)"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "IyVtnYHFRNNA"
      },
      "source": [
        "## 提取和重用层计算图中的节点\n",
        "\n",
        "由于要处理的层计算图是静态数据结构，可以对其进行访问和检查。而这就是将函数式模型绘制为图像的方式。\n",
        "\n",
        "这也意味着您可以访问中间层的激活函数（计算图中的“节点”）并在其他地方重用它们，这对于特征提取之类的操作十分有用。\n",
        "\n",
        "让我们来看一个例子。下面是一个 VGG19 模型，其权重已在 ImageNet 上进行了预训练："
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "id": "KCTLizyVyleq"
      },
      "outputs": [],
      "source": [
        "vgg19 = tf.keras.applications.VGG19()"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "viqPKrTHqggN"
      },
      "source": [
        "下面是通过查询计算图数据结构获得的模型的中间激活："
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "id": "liwRAiGhPjGy"
      },
      "outputs": [],
      "source": [
        "features_list = [layer.output for layer in vgg19.layers]"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "S7wQBJbX7tfy"
      },
      "source": [
        "使用以下特征来创建新的特征提取模型，该模型会返回中间层激活的值："
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "id": "UyNGDXbgd7Kp"
      },
      "outputs": [],
      "source": [
        "feat_extraction_model = keras.Model(inputs=vgg19.input, outputs=features_list)\n",
        "\n",
        "img = np.random.random((1, 224, 224, 3)).astype(\"float32\")\n",
        "extracted_features = feat_extraction_model(img)"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "XjoSeTbV8d6N"
      },
      "source": [
        "这尤其适用于诸如[神经样式转换](https://tensorflow.google.cn/tutorials/generative/style_transfer)之类的任务。"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "cL9HNbKS3uXj"
      },
      "source": [
        "## 使用自定义层扩展 API\n",
        "\n",
        "`tf.keras` 包含了各种内置层，例如：\n",
        "\n",
        "- 卷积层：`Conv1D`、`Conv2D`、`Conv3D`、`Conv2DTranspose`\n",
        "- 池化层：`MaxPooling1D`、`MaxPooling2D`、`MaxPooling3D`、`AveragePooling1D`\n",
        "- RNN 层：`GRU`、`LSTM`、`ConvLSTM2D`\n",
        "- `BatchNormalization`、`Dropout`、`Embedding` 等\n",
        "\n",
        "但是，如果找不到所需内容，可以通过创建您自己的层来方便地扩展 API。所有层都会子类化 `Layer` 类并实现下列方法：\n",
        "\n",
        "- `call` 方法，用于指定由层完成的计算。\n",
        "- `build` 方法，用于创建层的权重（这只是一种样式约定，因为您也可以在 `__init__` 中创建权重）。\n",
        "\n",
        "要详细了解从头开始创建层的详细信息，请阅读[自定义层和模型](https://tensorflow.google.cn/guide/keras/custom_layers_and_models)指南。\n",
        "\n",
        "以下是 `tf.keras.layers.Dense` 的基本实现："
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "id": "N0vptMTt8v6t"
      },
      "outputs": [],
      "source": [
        "class CustomDense(layers.Layer):\n",
        "    def __init__(self, units=32):\n",
        "        super(CustomDense, self).__init__()\n",
        "        self.units = units\n",
        "\n",
        "    def build(self, input_shape):\n",
        "        self.w = self.add_weight(\n",
        "            shape=(input_shape[-1], self.units),\n",
        "            initializer=\"random_normal\",\n",
        "            trainable=True,\n",
        "        )\n",
        "        self.b = self.add_weight(\n",
        "            shape=(self.units,), initializer=\"random_normal\", trainable=True\n",
        "        )\n",
        "\n",
        "    def call(self, inputs):\n",
        "        return tf.matmul(inputs, self.w) + self.b\n",
        "\n",
        "\n",
        "inputs = keras.Input((4,))\n",
        "outputs = CustomDense(10)(inputs)\n",
        "\n",
        "model = keras.Model(inputs, outputs)"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "9NzZWvTlcIN3"
      },
      "source": [
        "为了在您的自定义层中支持序列化，请定义一个 `get_config` 方法，返回层实例的构造函数参数："
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "id": "z6gBBzoCWOeo"
      },
      "outputs": [],
      "source": [
        "class CustomDense(layers.Layer):\n",
        "    def __init__(self, units=32):\n",
        "        super(CustomDense, self).__init__()\n",
        "        self.units = units\n",
        "\n",
        "    def build(self, input_shape):\n",
        "        self.w = self.add_weight(\n",
        "            shape=(input_shape[-1], self.units),\n",
        "            initializer=\"random_normal\",\n",
        "            trainable=True,\n",
        "        )\n",
        "        self.b = self.add_weight(\n",
        "            shape=(self.units,), initializer=\"random_normal\", trainable=True\n",
        "        )\n",
        "\n",
        "    def call(self, inputs):\n",
        "        return tf.matmul(inputs, self.w) + self.b\n",
        "\n",
        "    def get_config(self):\n",
        "        return {\"units\": self.units}\n",
        "\n",
        "\n",
        "inputs = keras.Input((4,))\n",
        "outputs = CustomDense(10)(inputs)\n",
        "\n",
        "model = keras.Model(inputs, outputs)\n",
        "config = model.get_config()\n",
        "\n",
        "new_model = keras.Model.from_config(config, custom_objects={\"CustomDense\": CustomDense})"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "aTTHlzrWMLvq"
      },
      "source": [
        "您也可以选择实现 `from_config(cls, config)` 类方法，该方法用于在给定其配置字典的情况下重新创建层实例。`from_config` 的默认实现如下：\n",
        "\n",
        "```python\n",
        "def from_config(cls, config):   return cls(**config)\n",
        "```"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "CleaIOquCbOs"
      },
      "source": [
        "## 何时使用函数式 API\n",
        "\n",
        "什么时候应该使用 Keras 函数式 API 来创建新的模型，或者什么时候应该直接对 `Model` 类进行子类化呢？通常来说，函数式 API 更高级、更易用且更安全，并且具有许多子类化模型所不支持的功能。\n",
        "\n",
        "但是，当构建不容易表示为有向无环的层计算图的模型时，模型子类化会提供更大的灵活性。例如，您无法使用函数式 API 来实现 Tree-RNN，而必须直接子类化 `Model` 类。\n",
        "\n",
        "要深入了解函数式 API 和模型子类化之间的区别，请阅读 [TensorFlow 2.0 符号式 API 和命令式 API 介绍](https://blog.tensorflow.org/2019/01/what-are-symbolic-and-imperative-apis.html)。\n",
        "\n",
        "### 函数式 API 的优势：\n",
        "\n",
        "下列属性对于序贯模型（也是数据结构）同样适用，但对于子类化模型（是 Python 字节码而非数据结构）则不适用。\n",
        "\n",
        "#### 更加简洁\n",
        "\n",
        "没有 `super(MyClass, self).__init__(...)`，没有 `def call(self, ...):` 等内容。\n",
        "\n",
        "对比：\n",
        "\n",
        "```python\n",
        "inputs = keras.Input(shape=(32,)) x = layers.Dense(64, activation='relu')(inputs) outputs = layers.Dense(10)(x) mlp = keras.Model(inputs, outputs)\n",
        "```\n",
        "\n",
        "下面是子类化版本：\n",
        "\n",
        "```python\n",
        "class MLP(keras.Model):    def __init__(self, **kwargs):     super(MLP, self).__init__(**kwargs)     self.dense_1 = layers.Dense(64, activation='relu')     self.dense_2 = layers.Dense(10)    def call(self, inputs):     x = self.dense_1(inputs)     return self.dense_2(x)  # Instantiate the model. mlp = MLP() # Necessary to create the model's state. # The model doesn't have a state until it's called at least once. _ = mlp(tf.zeros((1, 32)))\n",
        "```\n",
        "\n",
        "#### 定义连接计算图时进行模型验证\n",
        "\n",
        "在函数式 API 中，输入规范（形状和 dtype）是预先创建的（使用 `Input`）。每次调用层时，该层都会检查传递给它的规范是否符合其假设，如不符合，它将引发有用的错误消息。\n",
        "\n",
        "这样可以保证能够使用函数式 API 构建的任何模型都可以运行。所有调试（除与收敛有关的调试外）均在模型构造的过程中静态发生，而不是在执行时发生。这类似于编译器中的类型检查。\n",
        "\n",
        "#### 函数式模型可绘制且可检查\n",
        "\n",
        "您可以将模型绘制为计算图，并且可以轻松访问该计算图中的中间节点。例如，要提取和重用中间层的激活（如前面的示例所示），请运行以下代码：\n",
        "\n",
        "```python\n",
        "features_list = [layer.output for layer in vgg19.layers] feat_extraction_model = keras.Model(inputs=vgg19.input, outputs=features_list)\n",
        "```\n",
        "\n",
        "#### 函数式模型可以序列化或克隆\n",
        "\n",
        "因为函数式模型是数据结构而非一段代码，所以它可以安全地序列化，并且可以保存为单个文件，从而使您可以重新创建完全相同的模型，而无需访问任何原始代码。请参阅[序列化和保存](https://tensorflow.google.cn/guide/keras/save_and_serialize/)指南。\n",
        "\n",
        "要序列化子类化模型，实现器必须在模型级别指定 `get_config()` 和 `from_config()` 方法。\n",
        "\n",
        "### 函数式 API 的劣势：\n",
        "\n",
        "#### 不支持动态架构\n",
        "\n",
        "函数式 API 将模型视为层的 DAG。对于大多数深度学习架构来说确实如此，但并非所有（例如，递归网络或 Tree RNN 就不遵循此假设，无法在函数式 API 中实现）。"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "KoHEzhwdXaXo"
      },
      "source": [
        "## 混搭 API 样式\n",
        "\n",
        "在函数式 API 或模型子类化之间进行选择并非是让您作出二选一的决定而将您限制在某一类模型中。`tf.keras` API 中的所有模型都可以彼此交互，无论它们是 `Sequential` 模型、函数式模型，还是从头开始编写的子类化模型。\n",
        "\n",
        "您始终可以将函数式模型或 `Sequential` 模型用作子类化模型或层的一部分："
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "id": "GNqLDs1ClHRb"
      },
      "outputs": [],
      "source": [
        "units = 32\n",
        "timesteps = 10\n",
        "input_dim = 5\n",
        "\n",
        "# Define a Functional model\n",
        "inputs = keras.Input((None, units))\n",
        "x = layers.GlobalAveragePooling1D()(inputs)\n",
        "outputs = layers.Dense(1)(x)\n",
        "model = keras.Model(inputs, outputs)\n",
        "\n",
        "\n",
        "class CustomRNN(layers.Layer):\n",
        "    def __init__(self):\n",
        "        super(CustomRNN, self).__init__()\n",
        "        self.units = units\n",
        "        self.projection_1 = layers.Dense(units=units, activation=\"tanh\")\n",
        "        self.projection_2 = layers.Dense(units=units, activation=\"tanh\")\n",
        "        # Our previously-defined Functional model\n",
        "        self.classifier = model\n",
        "\n",
        "    def call(self, inputs):\n",
        "        outputs = []\n",
        "        state = tf.zeros(shape=(inputs.shape[0], self.units))\n",
        "        for t in range(inputs.shape[1]):\n",
        "            x = inputs[:, t, :]\n",
        "            h = self.projection_1(x)\n",
        "            y = h + self.projection_2(state)\n",
        "            state = y\n",
        "            outputs.append(y)\n",
        "        features = tf.stack(outputs, axis=1)\n",
        "        print(features.shape)\n",
        "        return self.classifier(features)\n",
        "\n",
        "\n",
        "rnn_model = CustomRNN()\n",
        "_ = rnn_model(tf.zeros((1, timesteps, input_dim)))"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "8QUuRDzMJLc1"
      },
      "source": [
        "您可以在函数式 API 中使用任何子类化层或模型，前提是它实现了遵循以下模式之一的 `call` 方法：\n",
        "\n",
        "- `call(self, inputs, **kwargs)` - 其中 `inputs` 是张量或张量的嵌套结构（例如张量列表），`**kwargs` 是非张量参数（非输入）。\n",
        "- `call(self, inputs, training=None, **kwargs)` - 其中 `training` 是指示该层是否应在训练模式和推断模式下运行的布尔值。\n",
        "- `call(self, inputs, mask=None, **kwargs)` - 其中 `mask` 是一个布尔掩码张量（对 RNN 等十分有用）。\n",
        "- `call(self, inputs, training=None, mask=None, **kwargs)` - 当然，您可以同时具有掩码和训练特有的行为。\n",
        "\n",
        "此外，如果您在自定义层或模型上实现了 `get_config` 方法，则您创建的函数式模型将仍可序列化和克隆。\n",
        "\n",
        "下面是一个从头开始编写、用于函数式模型的自定义 RNN 的简单示例："
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "id": "pO1Z07EOUIlE"
      },
      "outputs": [],
      "source": [
        "units = 32\n",
        "timesteps = 10\n",
        "input_dim = 5\n",
        "batch_size = 16\n",
        "\n",
        "\n",
        "class CustomRNN(layers.Layer):\n",
        "    def __init__(self):\n",
        "        super(CustomRNN, self).__init__()\n",
        "        self.units = units\n",
        "        self.projection_1 = layers.Dense(units=units, activation=\"tanh\")\n",
        "        self.projection_2 = layers.Dense(units=units, activation=\"tanh\")\n",
        "        self.classifier = layers.Dense(1)\n",
        "\n",
        "    def call(self, inputs):\n",
        "        outputs = []\n",
        "        state = tf.zeros(shape=(inputs.shape[0], self.units))\n",
        "        for t in range(inputs.shape[1]):\n",
        "            x = inputs[:, t, :]\n",
        "            h = self.projection_1(x)\n",
        "            y = h + self.projection_2(state)\n",
        "            state = y\n",
        "            outputs.append(y)\n",
        "        features = tf.stack(outputs, axis=1)\n",
        "        return self.classifier(features)\n",
        "\n",
        "\n",
        "# Note that you specify a static batch size for the inputs with the `batch_shape`\n",
        "# arg, because the inner computation of `CustomRNN` requires a static batch size\n",
        "# (when you create the `state` zeros tensor).\n",
        "inputs = keras.Input(batch_shape=(batch_size, timesteps, input_dim))\n",
        "x = layers.Conv1D(32, 3)(inputs)\n",
        "outputs = CustomRNN()(x)\n",
        "\n",
        "model = keras.Model(inputs, outputs)\n",
        "\n",
        "rnn_model = CustomRNN()\n",
        "_ = rnn_model(tf.zeros((1, 10, 5)))"
      ]
    }
  ],
  "metadata": {
    "colab": {
      "collapsed_sections": [],
      "name": "functional.ipynb",
      "toc_visible": true
    },
    "kernelspec": {
      "display_name": "Python 3",
      "name": "python3"
    }
  },
  "nbformat": 4,
  "nbformat_minor": 0
}
